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ABOUT THIS CHAPTER 


This chapter describes the Memory Manager, the part of the Macintosh Operating 
System that controls the dynamic allocation of memory space in the heap. 
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ABOUT THE MEMORY MANAGER 


Using the Memory Manager, your program can maintain one or more independent 
areas of heap memory (called heap zones) and use them to allocate blocks of 
memory of any desired size. Unlike stack space, which is always allocated and 
released in strict LIFO (last-in-first-out) order, blocks in the heap can be 
allocated and released in any order, according to your program's needs. So 
instead of growing and shrinking in an orderly way like the stack, the heap 
tends to become fragmented into a patchwork of allocated and free blocks, as 
shown in Figure 1. The Memory Manager does all the necessary "housekeeping" to 
keep track of the blocks as it allocates and releases them. 
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Figure 1—-Fragmented Heap 
Figure 1—Fragmented Heap 


The Memory Manager always maintains at least two heap zones: a system heap zone 
that's used by the Operating System and an application heap zone that's used by 
the Toolbox and your application program. The system heap zone is initialized to 
a fixed size when the system starts up. 


Note: The initial size of the system heap zone is determined by the system 
startup information stored on a volume; for more information, see the 
section "Data Organization on Volumes" in the File Manager chapter. 

The default initial size of this zone depends on the memory size of the 
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machine and may be different in future versions of the Macintosh. 


Objects in the system heap zone remain allocated even when one application 
terminates and another starts up. In contrast, the application heap zone is 
automatically reinitialized at the start of each new application program, and 
the contents of any previous application zone are lost. 


Assembly-language note: If desired, you can prevent the application heap 
zone from being reinitialized when an application 
starts up; see the discussion of the Chain procedure 
in the Segment Loader chapter for details. 


The initial size of the application zone is 6K bytes, but it can grow as needed. 
Your program can create additional heap zones if it chooses, either by 
subdividing this original application zone or by allocating space on the stack 
for more heap zones. 


Note: In this chapter, unless otherwise stated, the term "application heap 
zone" (or “application zone") always refers to the original application 
heap zone provided by the system, before any subdivision. 


Your program's code typically resides in the application zone, in space reserved 
for it at the request of the Segment Loader. Similarly, the Resource Manager 
requests space in the application zone to hold resources it has read into memory 
from a resource file. Toolbox routines that create new entities of various 
kinds, such as NewWindow, NewControl, and NewMenu, also call the Memory Manager 
to allocate the space they need. 


At any given time, there's one current heap zone, to which most Memory Manager 
operations implicitly apply. You can control which heap zone is current by 
calling a Memory Manager procedure. Whenever the system needs to access its own 
(system) heap zone, it saves the setting of the current heap zone and restores 
it later. 


Space within a heap zone is divided into contiguous pieces called blocks. The 
blocks in a zone fill it completely: Every byte in the zone is part of exactly 
one block, which may be either allocated (reserved for use) or free (available 
for allocation). Each block has a block header for the Memory Manager's own use, 
followed by the block's contents, the area available for use by your application 
or the system (see Figure 2). There may also be some unused bytes at the end of 
the block, beyond the end of the contents. A block can be of any size, limited 
only by the size of the heap zone itself. 


Assembly-language note: Blocks are always aligned on even word boundaries, 
SO you can access them with word (.W) and long-word 
(.L) instructions. 


An allocated block may be relocatable or nonrelocatable. Relocatable blocks can 
be moved around within the heap zone to create space for other blocks; 
nonrelocatable blocks can never be moved. These are permanent properties of a 
block. If relocatable, a block may be locked or unlocked; if unlocked, it may be 
purgeable or unpurgeable. These attributes can be set and changed as necessary. 
Locking a relocatable block prevents it from being moved. Making a block 
purgeable allows the Memory Manager to remove it from the heap zone, if 
necessary, to make room for another block. (Purging of blocks is discussed 
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further below under "How Heap Space Is Allocated".) A newly allocated 
relocatable block is initially unlocked and unpurgeable. 


Bock header— 


Coettartts — 


Urused bytes — 


Figure 2-A Block 


Figure 2—A Block 


Relocatable blocks are moved only by the Memory Manager, and only at well- 
defined, predictable times. In particular, only the routines listed in Appendix 
B can cause blocks to move, and these routines can never be called from within 
an interrupt. If your program doesn't call these routines, you can rely on 
blocks not being moved. 


Many existing Memory Manager routines have been improved; most of these 
improvements are transparent to the programmer. 


SetHandleSize is smarter about finding free space below, as well as above, the 
relocatable block. 


Routines have been provided for the setting and clearing of handle flags. 
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POINTERS AND HANDLES 


Relocatable and nonrelocatable blocks are referred to in different ways: 
nonrelocatable blocks by pointers, relocatable blocks by handles. When the 
Memory Manager allocates a new block, it returns a pointer or handle to the 
contents of the block (not to the block's header) depending on whether the block 
is nonrelocatable (Figure 3) or relocatable (Figure 4). 
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Figure 3-4 Pointer to a Nonrelocatable Block 
Figure 3—-A Pointer to a Nonrelocatable Block 


A pointer to a nonrelocatable block never changes, since the block itself can't 
move. A pointer to a relocatable block can change, however, since the block can 
move. For this reason, the Memory Manager maintains a single nonrelocatable 

master pointer to each relocatable block. The master pointer is created at the 
Same time as the block and set to point to it. When you allocate a relocatable 
block, the Memory Manager returns a pointer to the master pointer, called a 

handle to the block (see Figure 4). If the Memory Manager later has to move the 


block, it has only to update the master pointer to point to the block's new 
location. 
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Figure 4-A Handle to a Relocatable Block 


Figure 4—A Handle to a Relocatable Block 
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HOW HEAP SPACE IS ALLOCATED 


The Memory Manager allocates space for relocatable blocks according to a "first 
fit" strategy. It looks for a free block of at least the requested size, 
scanning forward from the end of the last block allocated and "wrapping around" 
from the top of the zone to the bottom if necessary. As soon as it finds a free 
block big enough, it allocates the requested number of bytes from that block. 


If a single free block can't be found that's big enough, the Memory Manager will 
try to create the needed space by compacting the heap zone: moving allocated 
blocks together in order to collect the free space into a single larger block. 
Only relocatable, unlocked blocks are moved. The compaction continues until 
either a free block of at least the requested size has been created or the 
entire heap zone has been compacted. Figure 5 illustrates what happens when the 
entire heap must be compacted to create a large enough free block. 


Nonrelocatable blocks (and relocatable ones that are temporarily locked) 
interfere with the compaction process by forming immovable "islands" in the 
heap. This can prevent free blocks from being collected together and lead to 
fragmentation of the available free space, as shown in Figure 6. (Notice that 
the Memory Manager will never move a relocatable block around a nonrelocatable 
block.) To minimize this problem, the Memory Manager tries to keep all the 
nonrelocatable blocks together at the bottom of the heap zone. When you allocate 
a nonrelocatable block, the Memory Manager will try to make room for the new 
block near the bottom of the zone, by moving other blocks upward, expanding the 
zone, or purging blocks from it (see below). 


Warning: To avoid heap fragmentation, use relocatable instead of 
nonrelocatable blocks. 
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Figure 5—Heap Compaction 
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Figure 6-—Framentation of Free Space 
Figure 6—Fragmentation of Free Space 


If the Memory Manager can't satisfy the allocation request after compacting the 
entire heap zone, it next tries expanding the zone by the requested number of 
bytes (rounded up to the nearest 1K bytes). Only the original application zone 
can be expanded, and only up to a certain limit (discussed more fully under 
"The Stack and the Heap"). If any other zone is current, or if the application 
zone has already reached or exceeded its limit, this step is skipped. 


Next the Memory Manager tries to free space by purging blocks from the zone. 
Only relocatable blocks can be purged, and then only if they're explicitly 
marked as unlocked and purgeable. Purging a block removes it from its heap zone 
and frees the space it occupies. The space occupied by the block's master 
pointer itself remains allocated, but the master pointer is set to NIL. Any 
handles to the block now point to a NIL master pointer, and are said to be 
empty. If your program later needs to refer to the purged block, it must detect 
that the handle has become empty and ask the Memory Manager to reallocate the 
block. This operation updates the master pointer (see Figure 7). 


Warning: Reallocating a block recovers only its space, not its contents 
(which were lost when the block was purged). It's up to your 
program to reconstitute the block's contents. 


Finally, if all else fails, the Memory Manager calls the grow zone function, if 
any, for the current heap zone. This is an optional routine that an application 
can provide to take any last-ditch measures to try to "grow" the zone by freeing 
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some space in it. The grow zone function can try to create additional free space 
by purging blocks that were previously marked unpurgeable, unlocking previously 
locked blocks, and so on. The Memory Manager will call the grow zone function 
repeatedly, compacting the heap again after each call, until either it finds the 
Space it's looking for or the grow zone function has exhausted all 
possibilities. In the latter case, the Memory Manager will finally give up and 
report that it's unable to satisfy the allocation request. 


Note: The Memory Manager moves a block by copying the entire block to a new 
location; it won't "slide" a block up or down in memory. If there isn't 
free space at least as large as the block, the block is effectively not 
relocatable. 


Dereferencing a Handle 


Accessing a block by double indirection, through its handle instead of through 
its master pointer, requires an extra memory reference. For efficiency, you may 
sometimes want to dereference the handle—that is, make a copy of the block's 
master pointer, and then use that pointer to access the block by single 
indirection. But be careful! Any operation that allocates space from the heap 
may cause the underlying block to be moved or purged. In that event, the master 
pointer itself will be correctly updated, but your copy of it will be left 
dangling. 


One way to avoid this common type of program bug is to lock the block before 
dereferencing its handle. For example: 


VAR aPointer: Ptr; 
aHandle: Handle; 


aHandle := NewHandle(...); {create relocatable block} 


HLock(aHandle) ; {lock before dereferencing} 
aPointer := aHandle’; {dereference handle} 
WHILE ... DO 
BEGIN 
...aPointer’... {use simple pointer} 
END; 
HUnlock(aHandle) {unlock block when finished} 
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Figure 7—Purging and Reallocating a Block 
Figure 7—Purging and Reallocating a Block 
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Assembly-language note: To dereference a handle in assembly language, just 
copy the master pointer into an address register 
and use it to access the block by single indirection. 


Remember, however, that when you lock a block it becomes an "island" in the heap 
that may interfere with compaction and cause free space to become fragmented. 
It's recommended that you use this technique only in parts of your program where 
efficiency is critical, such as inside tight inner loops that are executed many 
times (and that don't allocate other blocks). 


Warning: Don't forget to unlock the block again when you're through with 
the dereferenced handle. 


Instead of locking the block, you can update your copy of the master pointer 
after any "dangerous" operation (one that can invalidate the pointer by moving 
or purging the block it points to). For a complete list of all routines that may 
move or purge blocks, see Appendix B. 


The Lisa Pascal compiler frequently dereferences handles during its normal 
operation. You should take care to write code that will protect you when the 
compiler dereferences handles in the following cases: 


e Use of the WITH statement with a handle, such as 
WITH aHandle** DO ... 


e Assigning the result of a function that can move or purge blocks (or 
of any function in a package or another segment) to a field in a record 
referred to by a handle, such as 


aHandle**. field := NewHandle(...) 


A problem may arise because the compiler generates code that dereferences 
the handle before calling NewHandle—and NewHandle may move the block 
containing the field. 


¢ Passing an argument of more than four bytes referred to by a handle, to 
a routine that can move or purge a block or to any routine in a package 
or another segment. For example: 


TEUpdate(hTE**. viewRect,hTE) 
or 
DrawString(theControl**.contrlTitle) 


You can avoid having the compiler generate and use dangling pointers by locking 
a block before you use its handle in the above situations. Or you can use 
temporary variables, as in the following: 


temp := NewHandle(...); 
aHandle**. field := temp 
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THE STACK AND THE HEAP 


The LIFO nature of the stack makes it particularly convenient for memory 
allocation connected with the activation and deactivation of routines 
(procedures and functions). Each time a routine is called, space is allocated 
for a stack frame. The stack frame holds the routine's parameters, local 
variables, and return address. Upon exit from the routine, the stack frame is 
released, restoring the stack to the same state it was in when the routine was 
called. 


In Lisa Pascal, all stack management is done by the compiler. When you call a 
routine, the compiler generates code to reserve space if necessary for a 
function result, place the parameter values and return link on the stack, and 
jump to the routine. The routine can then allocate space on the stack for its 
own local variables. 


Before returning, the routine releases the stack space occupied by its local 
variables, return link, and parameters. If the routine is a function, it leaves 
its result on the stack for the calling program. 


The application heap zone and the stack share the same area in memory, growing 
toward each other from opposite ends (see Figure 8). Naturally it would be 
disastrous for either to grow so far that it collides with the other. To help 
prevent such collisions, the Memory Manager enforces a limit on how far the 
application heap zone can grow toward the stack. Your program can set this 
application heap limit to control the allotment of available space between the 
stack and the heap. 
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Figure $-The Stack and the Heap 


Figure 8—The Stack and the Heap 


The application heap limit marks the boundary between the space available for 
the application heap zone and the space reserved exclusively for the stack. At 
the start of each application program, the limit is initialized to allow 8k 
bytes for the stack. Depending on your program's needs, you can adjust the Limit 
to allow more heap space at the expense of the stack or vice versa. 


Assembly-language note: The global variables DefltStack and MinStack 
contain the default and minimum sizes of the 
stack, respectively. 


Notice that the limit applies only to expansion of the heap; it has no effect on 
how far the stack can expand. Although the heap can never expand beyond the 
limit into space reserved for the stack, there's nothing to prevent the stack 
from crossing the limit. It's up to you to set the limit low enough to allow for 
the maximum stack depth your program will ever need. 


Note: Regardless of the limit setting, the application zone is never 
allowed to grow to within 1K of the current end of the stack. This 
gives a little extra protection in case the stack is approaching the 
boundary or has crossed over onto the heap's side, and allows some 
safety margin for the stack to expand even further. 


To help detect collisions between the stack and the heap, a "stack sniffer" 
routine is run sixty times a second, during the Macintosh's vertical retrace 
interrupt. This routine compares the current ends of the stack and the heap and 
invokes the System Error Handler in case of a collision. 


The stack sniffer can't prevent collisions, it can only detect them after the 
fact: A lot of computation can take place in a sixtieth of a second. In fact, 
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the stack can easily expand into the heap, overwrite it, and then shrink back 
again before the next activation of the stack sniffer, escaping detection 
completely. The stack sniffer is useful mainly during software development; the 
alert box the System Error Handler displays can be confusing to your program's 
end user. Its purpose is to warn you, the programmer, that your program's stack 
and heap are colliding, so that you can adjust the heap limit to correct the 
problem before the user ever encounters it. 
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GENERAL-PURPOSE DATA TYPES 


The Memory Manager includes a number of type definitions for general-purpose 
use. The types listed below are explained in the Macintosh Memory Management: 
An Introduction chapter. 


TYPE SignedByte = -128..127; 

Byte = 0..255; 

Ptr = “SignedByte; 
Handle = SPtr: 

Str255 = STRING[255]; 
StringPtr = *$tr255; 
StringHandle = “StringPtr; 
ProcPtr = Ptr; 

Fixed = LONGINT; 


For specifying the sizes of blocks in the heap, the Memory Manager defines a 
special type called Size: 


TYPE Size = LONGINT; 


All Memory Manager routines that deal with block sizes expect parameters of type 
Size or return them as results. 
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MEMORY ORGANIZATION 


This section discusses the organization of memory in the Macintosh 128K, 512K, 
and XL. 


Note: The information presented in this section may be different in future 
versions of Macintosh system software. 


The organization of the Macintosh 128K and 512K RAM is shown in Figure 9. The 
variable names listed on the right in the figure refer to global variables for 
use by assembly-language programmers. 


@ SpInside Macintosh « Version 1.0 * November 1989 * Apple Computer 
THE MEMORY MANAGER e 19 of 54 


Size [hates] Variakla 


(MernTop) 
7a Main sound buffer 


(SanEasal 


Fab Be 
i 
A 


Pat hema screen hutter 


25 = [Currertis] 
7 
setcan | 
Jack 


Figure 9-Maicntosh 126K and 512K RAM 
Figure 9—Macintosh 128K and 512K RAM 


Assembly-language note: The global variables, shown in parentheses, contain 
the addresses of the indicated areas. Names identified 
as marking the end of an area actually refer to the 
address following the last byte in that area. 


The lowest 2816 bytes are used for system globals. Immediately following this 
are the system heap and the application space, which is memory available for 
dynamic allocation by applications. Most of the application space is shared 
between the stack and the application heap, with the heap growing forward from 
the bottom of the space and the stack growing backward from the top. The 
remainder of the application space is occupied by QuickDraw global variables, 
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the application's global variables, the application parameters, and the jump 
table. The application parameters are 32 bytes of memory located above the 
application globals; they're reserved for use by the system. The first 
application parameter is the address of the first QuickDraw global variable 
(thePort). The jump table is explained in the Segment Loader chapter. 


Note: Some development systems may place the QuickDraw global variables in 
a different location, but the first application parameter will always 
point to them. 


Assembly-language note: The location pointed to by register A5 will always 
point to the first QuickDraw global variable. 


At (almost) the very end of memory are the main sound buffer, used by the Sound 
Driver to control the sounds emitted by the built-in speaker and by the Disk 
Driver to control disk motor speed, and the main screen buffer, which holds the 
bit image to be displayed on the Macintosh screen. The area between the main 
screen and sound buffers is used by the System Error Handler. 


There are alternate screen and sound buffers for special applications. If you 
use either or both of these, the memory available for use by your application is 
reduced accordingly. The Segment Loader provides routines for specifying that an 
alternate screen or sound buffer will be used. 


Note: The alternate screen and sound buffers are only supported on the 
Macintosh 128K, 512K (including enhanced), Plus, and SE. 


The memory organization of a Macintosh XL is shown in Figure 10. 
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Figure 10—Macintosh XL RAM 
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MEMORY MANAGER DATA STRUCTURES 


This section discusses the internal data structures of the Memory Manager. You 
don't need to know this information if you're just using the Memory Manager 
routinely to allocate and release blocks of memory from the application heap 
zone. 


Ete 
header 


avrailable 
apace 


zone 
trailer 


Figure 11—Strocture of a Heap “one 


Figure 11-Structure of a Heap Zone 


Structure of Heap Zones 


Each heap zone begins with a 52-byte zone header and ends with a 12-byte zone 
trailer (see Figure 11). The header contains all the information the Memory 
Manager needs about that heap zone; the trailer is just a minimum-size free 
block (described in the next section) placed at the end of the zone as a marker. 
All the remaining space between the header and trailer is available for 
allocation. 


In Pascal, a heap zone is defined as a zone record of type Zone. It's always 
referred to with a zone pointer of type THz ("the heap zone"): 


TYPE THz = “Zone; 
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Zone = RECORD 


bkLim: Ptr; {zone trailer block} 
purgePtr: Ptr; {used internally} 

hFstFree: Ptr; {first free master pointer} 
zcbFree: LONGINT; {number of free bytes} 
gzProc: ProcPtr; {grow zone function} 
moreMast: INTEGER; {master pointers to allocate} 
flags: INTEGER; {used internally} 

cntRel: INTEGER; {not used} 

maxRel: INTEGER; {not used} 

cntNRel: INTEGER; {not used} 

maxNRelL: INTEGER; {not used} 

cntEmpty: INTEGER; {not used} 


cntHandles: INTEGER; {not used} 
minCBFree: LONGINT; {not used} 


purgeProc: ProcPtr; {purge warning procedure} 

SparePtr: Ptr; {used internally} 

allocPtr: Ptr; {used internally} 

heapData: INTEGER {first usable byte in zone} 
END; 


Warning: The fields of the zone header are for the Memory Manager's own 
internal use. You can examine the contents of the zone's fields, 
but in general it doesn't make sense for your program to try to 
change them. The few exceptions are noted below in the discussions 
of the specific fields. 


BkLim is a pointer to the zone's trailer block. Since the trailer is the last 
block in the zone, bkLim is a pointer to the byte following the last byte of 
usable space in the zone. 


HFstFree is a pointer to the first free master pointer in the zone. Instead of 
just allocating space for one master pointer each time a relocatable block is 
created, the Memory Manager "preallocates" several master pointers at a time; as 
a group they form a nonrelocatable block. The moreMast field of the zone record 
tells the Memory Manager how many master pointers at a time to preallocate for 
this zone. 


Note: Master pointers are allocated 32 at a time for the system heap zone 
and 64 at a time for the application zone; this may be different on 
future versions of the Macintosh. 


ALL master pointers that are allocated but not currently in use are linked 
together into a list beginning in the hFstFree field. When you allocate a new 
relocatable block, the Memory Manager removes the first available master pointer 
from this list, sets it to point to the new block, and returns its address to 
you as a handle to the block. (If the list is empty, it allocates a fresh block 
of moreMast master pointers.) When you release a relocatable block, its master 
pointer isn't released, but is linked onto the beginning of the list to be 
reused. Thus the amount of space devoted to master pointers can increase, but 
can never decrease until the zone is reinitialized. 


The zcbFree field always contains the number of free bytes remaining in the 
zone. As blocks are allocated and released, the Memory Manager adjusts zcbFree 
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accordingly. This number represents an upper limit on the size of block you can 
allocate from this heap zone. 


Warning: It may not actually be possible to allocate a block as big as 
zcbFree bytes. Because nonrelocatable and locked blocks can't be 
moved, it isn't always possible to collect all the free space into 
a single block by compaction. 


The gzProc field is a pointer to the grow zone function. You can supply a 
pointer to your own grow zone function when you create a new heap zone and can 
change it at any time. 


Warning: Don't store directly into the gzProc field; if you want to supply 
your own grow zone function, you must do so with a procedure call 
(InitZone or SetGrowZone) . 


PurgeProc is a pointer to the zone's purge warning procedure, or NIL if there is 
none. The Memory Manager will call this procedure before it purges a block from 
the zone. 


Warning: Whenever you call the Resource Manager with SetResPurge(TRUE), 
it installs its own purge warning procedure, overriding any purge 
warning procedure you've specified to the Memory Manager; for further 
details, see the Resource Manager chapter. 


The last field of a zone record, heapData, is a dummy field marking the bottom 
of the zone's usable memory space. 
HeapData nominally contains an integer, but this integer has no significance in 
itself—it's just the first two bytes in the block header of the first block in 
the zone. The purpose of the heapData field is to give you a way of locating the 
effective bottom of the zone. For example, if myZone is a zone pointer, then 
@(myZone*.heapData) 
is a pointer to the first usable byte in the zone, just as 
myZone*.bkLim 


is a pointer to the byte following the last usable byte in the zone. 


Structure of Blocks 


Every block in a heap zone, whether allocated or free, has a block header that 
the Memory Manager uses to find its way around in the zone. Block headers are 
completely transparent to your program. All pointers and handles to allocated 
blocks point to the beginning of the block's contents, following the end of the 
header. Similarly, all block sizes seen by your program refer to the block's 
logical size (the number of bytes in its contents) rather than its physical size 
(the number of bytes it actually occupies in memory, including the header and 
any unused bytes at the end of the block). 
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Since your program shouldn't normally have to deal with block headers directly, 
there's no Pascal record type defining their structure. A block header consists 
of eight bytes, as shown in Figure 12. 


31 24 23 0 


tag byte physical block size 


relocatable block: relative handle 
nonrelocatable block: pointer to heap zone 
free block: not used 


Figure 12. Block Header 
Figure 12—Block Header 


The first byte of the block header is the tag byte, discussed below. The next 
three bytes contain the block's physical size in bytes. Adding this number to 
the block's address gives the address of the next block in the zone. 


The contents of the second long word (four bytes) in the block header depend on 
the type of block. For relocatable blocks, it contains the block's relative 
handle: a pointer to the block's master pointer, expressed as an offset 
relative to the start of the heap zone rather than as an absolute memory 
address. Adding the relative handle to the zone pointer produces a true handle 
for this block. For nonrelocatable blocks, the second long word of the header is 
just a pointer to the block's zone. For free blocks, these four bytes are 
unused. 


The structure of a tag byte is shown in Figure 13. 


| ee ae Se Sa 0 


| L size correction 
not used 


00: free block 
01: nonrelocatable block 
10: relocatable block 


Figure 13. Tag Byte 
Figure 13—Tag Byte 


Assembly-language note: You can use the global constants tyBkFree, tyBkNRel, 
and tyBkRel to test whether the value of the tag 
byte indicates a free, nonrelocatable, or relocatable 
block, respectively. 


The "size correction" in the tag byte of a block header is the number of unused 
bytes at the end of the block, beyond the end of the block's contents. It's 
equal to the difference between the block's logical and physical sizes, 
excluding the eight bytes of overhead for the block header: 
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physicalSize = logicalSize + sizeCorrection + 8 
There are two reasons why a block may contain such unused bytes: 


¢ The Memory Manager allocates space only in even numbers of bytes. If 
the block's logical size is odd, an extra, unused byte is added at the 
end to keep the physical size even. 

¢ The minimum number of bytes in a block is 12. This minimum applies to 
all blocks, free as well as allocated. If allocating the required number 
of bytes from a free block would leave a fragment of fewer than 12 free 
bytes, the leftover bytes are included unused at the end of the newly 
allocated block instead of being returned to free storage. 


Structure of Master Pointers 


The master pointer to a relocatable block has the structure shown in Figure 14. 
The low-order three bytes of the long word contain the address of the block's 
contents. The high-order byte contains some flag bits that specify the block's 
current status. Bit 7 of this byte is the lock bit (1 if the block is locked, 0 
if it's unlocked); bit 6 is the purge bit (1 if the block is purgeable, 0 if 
it's unpurgeable). Bit 5 is used by the Resource Manager to identify blocks 
containing resource information; such blocks are marked by a 1 in this bit. 


7654 0 


|| | | not used | address of block’s contents 
| L resource bit 
purge bit 
lock bit 


Figure 14. Structure of a Master Pointer 
Figure 14-Structure of a Master Pointer 


Warning: Note that the flag bits in the high-order byte have numerical 
Significance in any operation performed on a master pointer. For 
example, the lock bit is also the sign bit. 


Assembly-language note: You can use the mask in the global variable 
Lo3Bytes to determine the value of the low-order 
three bytes of a master pointer. To determine the 
value of bits 5, 6, and 7, you can use the global 
constants resourc, purge, and lock, respectively. 
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USING THE MEMORY MANAGER 


There's ordinarily no need to initialize the Memory Manager before using it. The 
system heap zone is automatically initialized each time the system starts up, 
and the application heap zone each time an application program starts up. In the 
unlikely event that you need to reinitialize the application zone while your 
program is running, you can call InitApplZone. 


When your application starts up, it should allocate the memory it requires in 
the most space-efficient manner possible, ensuring that most of the 
nonrelocatable blocks it will need are packed together at the bottom of the 
heap. The main segment of your program should call the MaxApplZone procedure, 
which expands the application heap zone to its limit. Then call the procedure 
MoreMasters repeatedly to allocate as many blocks of master pointers as your 
application and any desk accessories will need. Next initialize QuickDraw and 
the Window Manager (if you're going to use it). 


To allocate a new relocatable block, use NewHandle; for a nonrelocatable block, 

use NewPtr. These functions return a handle or a pointer, as the case may be, to 
the newly allocated block. To release a block when you're finished with it, use 

DisposHandle or DisposPtr. 


You can also change the size of an already allocated block with SetHandleSize or 
SetPtrSize, and find out its current size with GetHandleSize or GetPtrSize. Use 
HLock and HUnlock to lock and unlock relocatable blocks. Before locking a 
relocatable block, call MoveHHi. 


Note: If you lock a relocatable block, unlock it at the earliest possible 
opportunity. Before allocating a block that you know will be locked 
for long periods of time, call ResrvMem to make room for the block 
as near as possible to the bottom of the zone. 


In some situations it may be desirable to determine the handle that points to a 
given master pointer. To do this you can call the RecoverHandle function. For 
example, a relocatable block of code might want to find out the handle that 
refers to it, so it can lock itself down in the heap. 


Ordinarily, you shouldn't have to worry about compacting the heap or purging 
blocks from it; the Memory Manager automatically takes care of this for you. You 
can control which blocks are purgeable with HPurge and HNoPurge. If for some 
reason you want to compact or purge the heap explicitly, you can do so with 
CompactMem or PurgeMem. To explicitly purge a specific block, use EmptyHandle. 


Warning: Before attempting to access any purgeable block, you must check 
its handle to make sure the block is still allocated. If the handle 
is empty, then the block has been purged; before accessing it, you 
have to reallocate it by calling ReallocHandle, and then recreate 
its contents. (If it's a resource block, just call the Resource 
Manager procedure LoadResource; it checks the handle and reads the 
resource into memory if it's not already in memory.) 
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You can find out how much free space is left in a heap zone by calling FreeMem 
(to get the total number of free bytes) or MaxMem (to get the size of the 
largest single free block and the maximum amount by which the zone can grow). 
Beware: MaxMem compacts the entire zone and purges all purgeable blocks. To 
determine the current application heap limit, use GetApplLimit; to limit the 
growth of the application zone, use SetApplLimit. To install a grow zone 
function to help the Memory Manager allocate space in a zone, use SetGrowZone. 


You can create additional heap zones for your program's own use, either within 
the original application zone or in the stack, with InitZone. If you do maintain 
more than one heap zone, you can find out which zone is current at any given 
time with GetZone and switch from one to another with SetZone. Almost all Memory 
Manager operations implicitly apply to the current heap zone. To refer to the 
system heap zone or the (original) application heap zone, use the Memory Manager 
function SystemZone or ApplicZone. To find out which zone a particular block 
resides in, use HandleZone (if the block is relocatable) or PtrZone (if it's 
nonrelocatable) . 


Warning: Be sure, when calling routines that access blocks, that the zone 
in which the block is located is the current zone. 


Note: Most applications will just use the original application heap zone 
and never have to worry about which zone is current. 


After calling any Memory Manager routine, you can determine whether it was 
successfully completed or failed, by calling MemError. 


Warning: Code that will be executed via an interrupt must not make any 
calls to the Memory Manager, directly or indirectly, and can't 
depend on handles to unlocked blocks being valid. 
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MEMORY MANAGER ROUTINES 


In addition to their normal results, many Memory Manager routines yield a result 
code that you can examine by calling the MemError function. The description of 
each routine includes a list of all result codes it may yield. 


Assembly-language note: When called from assembly Language, not all Memory 
Manager routines return a result code. Those that do 
always leave it as a word-length quantity in the 
low-order word of register DO on return from the trap. 
However, some routines leave something else there 
instead; see the descriptions of individual routines 
for details. Just before returning, the trap 
dispatcher tests the low-order word of DO with a 
TST.W instruction, so that on return from the trap 
the condition codes reflect the status of the result 


code, if any. 


The stack-based interface routines called from Pascal 
always yield a result code. If the underlying trap 


doesn't return one, the interfa 


ce routine 


"manufactures" a result code of noErr and stores it 
where it can later be accessed with MemError. 


Assembly-language note: You can specify that some Memory Manager routines 
apply to the system heap zone instead of the current 
zone by setting bit 10 of the routine trap word. If 
you're using the Lisa Workshop Assembler, you do this 
by supplying the word SYS (uppercase) as the second 


argument to the routine macro: 


_FreeMem ,SYS 


If you want a block of memory to be cleared to zeroes 
when it's allocated by a NewPtr or NewHandle call, set 
bit 9 of the routine trap word. You can do this by 
supplying the word CLEAR (uppercase) as the second 


argument to the routine macro: 


_NewHandle ,CLEAR 


You can combine SYS and CLEAR in the same macro call, 


but SYS must come first: 


_NewHandle ,SYS,CLEAR 


The description of each routine lists whether SYS or 
CLEAR is applicable. (The syntax shown above and in 
the routine descriptions applies to the Lisa Workshop 
Assembler; programmers using another development 
system should consult its documentation for the 
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proper syntax.) 


Two Memory Manager routines—MaxApplZone and MoveHHi-that were not in the 64K ROM 
have been added to the 128K ROM. 


Initialization and Allocation 
PROCEDURE InitApplZone; 


Trap macro —InitApplZone 
On exit DO: result code (word) 


InitApplZone initializes the application heap zone and makes it the current 
zone. The contents of any previous application zone are lost; all previously 
existing blocks in that zone are discarded. The zone's grow zone function is set 
to NIL. InitApplZone is called by the Segment Loader when starting up an 
application; you shouldn't normally need to call it. 


Warning: Reinitializing the application zone from within a running program 
is tricky, since the program's code itself normally resides in the 
application zone. To do it safely, the code containing the 
InitApplZone call cannot be in the application zone. 


Result codes noErr No error 
PROCEDURE SetApplBase (startPtr: Ptr); 


Trap macro —_SetAppBase 
On entry AO: startPtr (pointer) 
On exit DO: result code (word) 


SetApplBase changes the starting address of the application heap zone to the 
address designated by startPtr, and then calls InitApplZone. SetApplBase is 
normally called only by the system itself; you should never need to call this 
procedure. 


Since the application heap zone begins immediately following the end of the 
system zone, changing its starting address has the effect of changing the size 
of the system zone. The system zone can be made larger, but never smaller; if 
startPtr points to an address lower than the current end of the system zone, 
it's ignored and the application zone's starting address is left unchanged. 


Warning: Like InitApplZone, SetApplBase is a tricky operation, because the 
program's code itself normally resides in the application heap zone. 
To do it safely, the code containing the SetApplBase call cannot be 
in the application zone. 

Result codes noErr No error 


PROCEDURE InitZone (pGrowZone: ProcPtr; cMoreMasters: INTEGER; 
LimitPtr,startPtr: Ptr); 


Trap macro —_InitZone 
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On entry AO: pointer to parameter block 


Parameter block 


0 startPtr pointer 
4 LimitPtr pointer 
8 cMoreMasters word 
10 pGrowZone pointer 
On exit DO: result code (word) 


InitZone creates a new heap zone, initializes its header and trailer, and makes 
it the current zone. The startPtr parameter is a pointer to the first byte of 
the new zone; LimitPtr points to the first byte beyond the end of the zone. The 
new zone will occupy memory addresses from ORD(startPtr) through 
ORD(LimitPtr)—-1. 


CMoreMasters tells how many master pointers should be allocated at a time for 
the new zone. This number of master pointers are created initially; should more 
be needed later, they'll be added in increments of this same number. 


The pGrowZone parameter is a pointer to the grow zone function for the new zone, 
if any. If you're not defining a grow zone function for this zone, pass NIL. 


The new zone includes a 52-byte header and a 12-byte trailer, so its actual 
usable space runs from ORD(startPtr)+52 through ORD(limitPtr)—13. In addition, 
there's an eight-byte header for the master pointer block, as well as four bytes 
for each master pointer, within this usable area. Thus the total available space 
in the zone, in bytes, is initially 


ORD(LimitPtr) — ORD(startPtr) — 64 — (8 + (4*cMoreMasters) ) 


This number must not be less than 0. Note that the amount of available space in 
the zone will decrease as more master pointers are allocated. 


Result codes noErr No error 
FUNCTION GetApplLimit : Ptr; [Not in ROM] 


GetApplLimit returns the current application heap limit. It can be used in 
conjunction with SetApplLimit, described below, to determine and then change the 
application heap limit. 


Assembly-language note: The global variable ApplLimit contains the 
current application heap limit. 


PROCEDURE SetAppLLimit (zoneLimit: Ptr); 


Trap macro SetApplLimit 
On entry AQ: zoneLimit (pointer) 
On exit DO: result code (word) 


SetApplLimit sets the application heap limit, beyond which the application heap 
can't be expanded. The actual expansion isn't under your program's control, but 
is done automatically by the Memory Manager when necessary to satisfy allocation 
requests. Only the original application zone can be expanded. 
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ZoneLimit is a pointer to a byte in memory beyond which the zone will not be 
allowed to grow. The zone can grow to include the byte preceding zoneLimit in 
memory, but no farther. If the zone already extends beyond the specified limit 
it won't be cut back, but it will be prevented from growing any more. 

Warning: Notice that zoneLimit is not a byte count. To limit the application 
zone to a particular size (say 8K bytes), you have to write something 
like 

SetAppLLimit (Ptr (ApplicZone) +8192) 
The Memory Manager function ApplicZone is explained below. 


Assembly-language note: You can just store the new application heap 
limit in the global variable ApplLimit. 


Result codes noErr No error 
memFullErr Not enough room in heap zone 


PROCEDURE MaxApplZone; [Not in 64K ROM] 


Trap macro _MaxApplZone 
On exit DO: result code (word) 


MaxApplZone expands the application heap zone to the application heap limit 
without purging any blocks currently in the zone. If the zone already extends to 
the limit, it won't be changed. 
Assembly-language note: To expand the application heap zone to the 
application heap limit from assembly Language, 
call this Pascal procedure from your program. 
Result codes noErr No error 
PROCEDURE MoreMasters; 
Trap macro _MoreMasters 


MoreMasters allocates another block of master pointers in the current heap zone. 
This procedure is usually called very early in an application. 


Result codes noErr No error 
memFullErr Not enough room in heap zone 


Heap Zone Access 
FUNCTION GetZone : THz; 
Trap macro _GetZone 


On exit AO: function result (pointer) 
DO: result code (word) 
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GetZone returns a pointer to the current heap zone. 


Assembly-language note: The global variable TheZone contains a 
pointer to the current heap zone. 


Result codes noErr No error 
PROCEDURE SetZone (hz: THz); 

Trap macro _SetZone 

On entry AO: hz (pointer) 

On exit DO: result code (word) 


SetZone sets the current heap zone to the zone pointed to by hz. 


Assembly-language note: You can set the current heap zone by storing 
a pointer to it in the global variable TheZone. 


Result codes noErr No error 
FUNCTION SystemZone : THz; [Not in ROM] 
SystemZone returns a pointer to the system heap zone. 


Assembly-language note: The global variable SysZone contains 
a pointer to the system heap zone. 


FUNCTION ApplicZone : THz; [Not in ROM] 
ApplicZone returns a pointer to the original application heap zone. 


Assembly-language note: The global variable ApplZone contains 
a pointer to the original application heap zone. 


Allocating and Releasing Relocatable Blocks 
FUNCTION NewHandle (logicalSize: Size) : Handle; 


Trap macro _NewHandle 
_NewHandle ,SYS (applies to system heap) 
_NewHandle ,CLEAR (clears allocated block) 
_NewHandle ,SYS,CLEAR (applies to system heap and clears 

allocated block) 

On entry DO: logicalSize (long word) 

On exit AQ: function result (handle) 
DO: result code (word) 


NewHandle attempts to allocate a new relocatable block of logicalSize bytes from 
the current heap zone and then return a handle to it. The new block will be 
unlocked and unpurgeable. If logicalSize bytes can't be allocated, NewHandle 
returns NIL. 
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NewHandle will pursue all available avenues to create a free block of the 
requested size, including compacting the heap zone, increasing its size, purging 
blocks from it, and calling its grow zone function, if any. 


Result codes noErr No error 
memFullErr Not enough room in heap zone 


PROCEDURE DisposHandle (h: Handle); 


Trap macro _DisposHandle 
On entry AO: h (handle) 
On exit DO: result code (word) 


DisposHandle releases the memory occupied by the relocatable block whose handle 
is h. 


Warning: After a call to DisposHandle, all handles to the released block 
become invalid and should not be used again. Any subsequent calls 
to DisposHandle using an invalid handle will damage the master 
pointer list. 


Result codes noErr No error 
memWZErr Attempt to operate on a free block 


FUNCTION GetHandleSize (h: Handle) : Size; 


Trap macro —_GetHandleSize 

On entry AO: h (handle) 

On exit DO: if >= 0, function result (long word) 
if < 0, result code (word) 


GetHandleSize returns the logical size, in bytes, of the relocatable block whose 
handle is h. In case of an error, GetHandleSize returns 0. 


Assembly-language note: Recall that the trap dispatcher sets the condition 
codes before returning from a trap by testing the 
low-order word of register DO with a TST.W instruction. 
Since the block size returned in DO by GetHandleSize 
is a full 32-bit long word, the word-length test sets 
the condition codes incorrectly in this case. To 
branch on the contents of DO, use your own TST.L 
instruction on return from the trap to test the full 
32 bits of the register. 


Result codes noErr No error [Pascal only] 
nilHandleErr NIL master pointer 
memWZErr Attempt to operate on a free block 


PROCEDURE SetHandleSize (h: Handle; newSize: Size); 


Trap macro _SetHandleSize 
On entry AQ: h (handle) 

DO: newSize (long word) 
On exit DO: result code (word) 
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SetHandleSize changes the logical size of the relocatable block whose handle is 
h to newSize bytes. 


Note: Be prepared for an attempt to increase the size of a locked block to 
fail, since there may be a block above it that's either nonrelocatable 


or locked. 
Result codes noErr No error 
memFullErr Not enough room in heap zone 
nilHandleErr NIL master pointer 
memWZErr Attempt to operate on a free block 


FUNCTION HandleZone (h: Handle) : THz; 


Trap macro _HandleZone 

On entry AO: h (handle) 

On exit AQ: function result (pointer) 
DO: result code (word) 


HandleZone returns a pointer to the heap zone containing the relocatable block 
whose handle is h. In case of an error, the result returned by HandleZone is 
undefined and should be ignored. 


Warning: If handle h is empty (points to a NIL master pointer), HandleZone 
returns a pointer to the current heap zone. 


Result codes noErr No error 
memWZErr Attempt to operate on a free block 


FUNCTION RecoverHandle (p: Ptr) : Handle; 


Trap macro _RecoverHandle 

_RecoverHandle ,SYS (applies to system heap) 
On entry AQ: p (pointer) 
On exit AO: function result (handle) 

DO: unchanged 


RecoverHandle returns a handle to the relocatable block pointed to by p. 


Assembly-language note: The trap RecoverHandle doesn't return a result 
code in register D0; the previous contents of DO 
are preserved unchanged. 


Result codes noErr No error [Pascal only] 
PROCEDURE ReallocHandle (h: Handle; logicalSize: Size); 


Trap macro _ReallocHandle 
On entry AO: h (handle) 

DO: tlogicalSize (long word) 
On exit DO: result code (word) 


ReallocHandle allocates a new relocatable block with a logical size of 
logicalSize bytes. It then updates handle h by setting its master pointer to 
point to the new block. The main use of this procedure is to reallocate space 
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for a block that has been purged. Normally h is an empty handle, but it need not 
be: If it points to an existing block, that block is released before the new 
block is created. 


In case of an error, no new block is allocated and handle h is left unchanged. 


Result codes noErr No error 
memFullErr Not enough room in heap zone 
memWZErr Attempt to operate on a free block 
memPurErr Attempt to purge a locked block 


Allocating and Releasing Nonrelocatable Blocks 
FUNCTION NewPtr (logicalSize: Size) : Ptr; 


Trap macro _NewPtr 
_NewPtr ,SYS (applies to system heap) 
_NewPtr ,CLEAR (clears allocated block) 
_NewPtr ,SYS,CLEAR (applies to system heap and clears 
allocated block) 
On entry DO: tlogicalSize (long word) 
On exit AO: function result (pointer) 
DO: result code (word) 


NewPtr attempts to allocate a new nonrelocatable block of logicalSize bytes from 
the current heap zone and then return a pointer to it. If logicalSize bytes 
can't be allocated, NewPtr returns NIL. 


NewPtr will pursue all available avenues to create a free block of the requested 
size at the lowest possible location in the heap zone, including compacting the 
heap zone, increasing its size, purging blocks from it, and calling its grow 
zone function, if any. 


Result codes noErr No error 
memFullErr Not enough room in heap zone 


PROCEDURE DisposPtr (p: Ptr); 


Trap macro _DisposPtr 
On entry AO: p (pointer) 
On exit DO: result code (word) 


DisposPtr releases the memory occupied by the nonrelocatable block pointed to by 
p. 


Warning: After a call to DisposPtr, all pointers to the released block 
become invalid and should not be used again. Any subsequent calls 
to DisposPtr using an invalid pointer will damage the master 
pointer list. 


Result codes noErr No error 
memWZErr Attempt to operate on a free block 
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FUNCTION GetPtrSize (p: Ptr) : Size; 


Trap macro GetPtrSize 

On entry AO: p (pointer) 

On exit DO: if >= 0, function result (long word) 
if < 0, result code (word) 


GetPtrSize returns the logical size, in bytes, of the nonrelocatable block 
pointed to by p. In case of an error, GetPtrSize returns 0. 


Assembly-language note: Recall that the trap dispatcher sets the condition 
codes before returning from a trap by testing the 
low-order word of register DO with a TST.W instruction. 
Since the block size returned in DO by GetPtrSize is 
a full 32-bit long word, the word-length test sets the 
condition codes incorrectly in this case. To branch on 
the contents of DO, use your own TST.L instruction on 
return from the trap to test the full 32 bits of the 


register. 
Result codes noErr No error [Pascal only] 
memWZErr Attempt to operate on a free block 


PROCEDURE SetPtrSize (p: Ptr; newSize: Size); 


Trap macro SetPtrSize 
On entry AQ: p (pointer) 

DO: newSize (long word) 
On exit DO: result code (word) 


SetPtrSize changes the logical size of the nonrelocatable block pointed to by p 
to newSize bytes. 


Result codes noErr No error 
memFullErr Not enough room in heap zone 
memWZErr Attempt to operate on a free block 


FUNCTION PtrZone (p: Ptr) : THz; 


Trap macro _PtrZone 

On entry AQ: p (pointer) 

On exit AQ: function result (pointer) 
DO: result code (word) 


PtrZone returns a pointer to the heap zone containing the nonrelocatable block 
pointed to by p. In case of an error, the result returned by PtrZone is 
undefined and should be ignored. 


Result codes noErr No error 
memWZErr Attempt to operate on a free block 


Freeing Space in the Heap 
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FUNCTION FreeMem : LONGINT; 


Trap macro —FreeMem 
_FreeMem ,SYS (applies to system heap) 
On exit DO: function result (long word) 


FreeMem returns the total amount of free space in the current heap zone, in 
bytes. Note that it usually isn't possible to allocate a block of this size, 
because of fragmentation due to nonrelocatable or locked blocks. 


Result codes noErr No error [Pascal only] 
FUNCTION MaxMem (VAR grow: Size) : Size; 


Trap macro _MaxMem 

_MaxMem ,SYS (applies to system heap) 
On exit DO: function result (long word) 

AQ: grow (long word) 


MaxMem compacts the current heap zone and purges all purgeable blocks from the 
zone. It returns as its result the size in bytes of the largest contiguous free 
block in the zone after the compaction. If the current zone is the original 
application heap zone, the grow parameter is set to the maximum number of bytes 
by which the zone can grow. For any other heap zone, grow is set to 0. MaxMem 
doesn't actually expand the zone or call its grow zone function. 


Result codes noErr No error [Pascal only] 
FUNCTION CompactMem (cbNeeded: Size) : Size; 


Trap macro —_CompactMem 

_CompactMem ,SYS (applies to system heap) 
On entry DO: cbNeeded (long word) 
On exit DO: function result (long word) 


CompactMem compacts the current heap zone by moving relocatable blocks down and 
collecting free space together until a contiguous block of at least cbNeeded 
free bytes is found or the entire zone is compacted; it doesn't purge any 
purgeable blocks. CompactMem returns the size in bytes of the largest contiguous 
free block remaining. Note that it doesn't actually allocate the block. 


Result codes noErr No error [Pascal only] 
PROCEDURE ResrvMem (cbNeeded: Size); 


Trap macro —ResrvMem 

_ResrvMem ,SYS (applies to system heap) 
On entry DO: cbNeeded (long word) 
On exit DO: result code (word) 


ResrvMem creates free space for a block of cbhNeeded contiguous bytes at the 
lowest possible position in the current heap zone. It will try every available 
means to place the block as close as possible to the bottom of the zone, 
including moving other blocks upward, expanding the zone, or purging blocks from 
it. Note that ResrvMem doesn't actually allocate the block. 
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Note: When you allocate a relocatable block that you know will be locked for 
long periods of time, call ResrvMem first. This reserves space for the 
block near the bottom of the heap zone, where it will interfere with 
compaction as little as possible. It isn't necessary to call ResrvMem 
for a nonrelocatable block; NewPtr calls it automatically. It's also 
called automatically when locked resources are read into memory. 


Result codes noErr No error 
memFullErr Not enough room in heap zone 


PROCEDURE PurgeMem (cbNeeded: Size); 


Trap macro —PurgeMem 

_PurgeMem ,SYS (applies to system heap) 
On entry DO: cbNeeded (long word) 
On exit DO: result code (word) 


PurgeMem sequentially purges blocks from the current heap zone until a 
contiguous block of at least cbNeeded free bytes is created or the entire zone 
is purged; it doesn't compact the heap zone. Only relocatable, unlocked, 
purgeable blocks can be purged. Note that PurgeMem doesn't actually allocate the 
block. 


Result codes noErr No error 
memFullErr Not enough room in heap zone 


PROCEDURE EmptyHandle (h: Handle); 


Trap macro —_EmptyHandle 
On entry AQ: h (handle) 
On exit AQ: h (handle) 
DO: result code (word) 


EmptyHandle purges the relocatable block whose handle is h from its heap zone 
and sets its master pointer to NIL (making it an empty handle). If h is already 
empty, EmptyHandle does nothing. 


Note: Since the space occupied by the block's master pointer itself remains 
allocated, all handles pointing to it remain valid but empty. When you 
later reallocate space for the block with ReallocHandle, the master 
pointer will be updated, causing all existing handles to access the 
new block correctly. 


The block whose handle is h must be unlocked, but need not be purgeable. 
Result codes noErr No error 


memWZErr Attempt to operate on a free block 
memPurErr Attempt to purge a locked block 


Properties of Relocatable Blocks 
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The master pointer associated with each handle contains flags for use by the 
Memory Manager. Routines are provided for setting and clearing each of these 
flags, as well as for saving and restoring the entire byte. 


Warning: Failure to use these routines virtually guarantees incompatibility 
with future versions of the Macintosh. You should not set and clear 
these flags directly. 


The HLock and HUnlock procedures lock and unlock a given relocatable block by 
setting and clearing the lock flag. The HPurge and HNoPurge mark a given 
relocatable block as purgeable or unpurgeable by setting and clearing the purge 
flag. 


A third flag, the resource flag, is used internally by the Resource Manager. The 
HSetRBit and HCLrRBit procedures set and clear this flag. 

The HSetState and HGetState routines let you save and restore the state of the 
flags byte. 


PROCEDURE HLock (h: Handle); 

Trap macro —HLock 

On entry AO: h (handle) 

On exit DO: result code (word) 


HLock locks a relocatable block, preventing it from being moved within its heap 
zone. If the block is already locked, HLock does nothing. 


Warning: To prevent heap fragmentation, you should always call MoveHHi 
before locking a relocatable block. 


Result codes noErr No error 
nilHandleErr NIL master pointer 
memWZErr Attempt to operate on a free block 


PROCEDURE HUnlock (h: Handle); 


Trap macro —HUnlock 
On entry AO: h (handle) 
On exit DO: result code (word) 


HUnlock unlocks a relocatable block, allowing it to be moved within its heap 
zone. If the block is already unlocked, HUnlock does nothing. 


Result codes noErr No error 
nilHandleErr NIL master pointer 
memWZErr Attempt to operate on a free block 


PROCEDURE HPurge (h: Handle); 


Trap macro _HPurge 
On entry AO: h (handle) 
On exit DO: result code (word) 


HPurge marks a relocatable block as purgeable. If the block is already 
purgeable, HPurge does nothing. 
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Note: If you call HPurge on a locked block, it won't unlock the block, but 
it will mark the block as purgeable. If you later call HUnlock, the 
block will be subject to purging. 


Result codes noErr No error 
nilHandleErr NIL master pointer 
memWZErr Attempt to operate on a free block 


PROCEDURE HNoPurge (h: Handle); 


Trap macro —HNoPurge 
On entry AO: h (handle) 
On exit DO: result code (word) 


HNoPurge marks a relocatable block as unpurgeable. If the block is already 
unpurgeable, HNoPurge does nothing. 


Result codes noErr No error 
nilHandleErr NIL master pointer 
memWZErr Attempt to operate on a free block 


PROCEDURE HSetRBit (h: Handle); 


Trap macro —_HSetRBit 
On entry AO: h (handle) 
On exit DO: result code (word) 


HSetRBit sets the resource flag of a relocatable block's master pointer. 
PROCEDURE HCIrRBit (h: Handle); 


Trap macro _HClrRBit 
On entry AO: h (handle) 
On exit DO: result code (word) 


HCLrRBit clears the resource flag of a relocatable block's master pointer. 
FUNCTION HGetState (h: Handle) : SignedByte; 


Trap macro _HGetState 
On entry AO: h (handle) 
On exit DO: flags (byte) 


HGetState returns the byte that contains the flags of the master pointer for the 
given handle; it's used in conjunction with HSetState to save and restore the 
state of the flags contained in this byte. You can save this byte, change the 
state of any of the flags (using the routines described above), and then restore 
their original state by passing the byte back to the HSetState procedure 
(described below). 


PROCEDURE HSetState (h: Handle; flags: SignedByte) ; 


Trap macro _HSetState 
On entry AO: h (handle) 
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DO: flags (byte) 
On exit DO: result code (word) 


HSetState is used in conjunction with HGetState; it sets the byte that contains 
the flags of the master pointer for the given handle to the byte specified by 
flags. 


Grow Zone Operations 
PROCEDURE SetGrowZone (growZone: ProcPtr); 


Trap macro —_SetGrowZone 
On entry AQ: growZone (pointer) 
On exit DO: result code (word) 


SetGrowZone sets the current heap zone's grow zone function as designated by the 
growZone parameter. A NIL parameter value removes any grow zone function the 
zone may previously have had. 


Note: If your program presses the limits of the available heap space, it's 
a good idea to have a grow zone function of some sort. At the very 
least, the grow zone function should take some graceful action—such 
as displaying an alert box with the message "Out of memory"—instead 

of just failing unpredictably. 


If it has failed to create a block of the needed size after compacting the zone, 
increasing its size (in the case of the original application zone), and purging 
blocks from it, the Memory Manager calls the grow zone function as a last 
resort. 


The grow zone function should be of the form 
FUNCTION MyGrowZone (cbNeeded: Size) : LONGINT; 


The cbhbNeeded parameter gives the physical size of the needed block in bytes, 
including the block header. The grow zone function should attempt to create a 
free block of at least this size. It should return a nonzero number if it's able 
to allocate some memory, or 0 if it's not able to allocate any. 


If the grow zone function returns 0, the Memory Manager will give up trying to 
allocate the needed block and will signal failure with the result code 
memFullErr. Otherwise it will compact the heap zone and try again to allocate 
the block. If still unsuccessful, it will continue to call the grow zone 
function repeatedly, compacting the zone again after each call, until it either 
succeeds in allocating the needed block or receives a zero result and gives up. 


The usual way for the grow zone function to free more space is to call 
EmptyHandle to purge blocks that were previously marked unpurgeable. Another 
possibility is to unlock blocks that were previously locked 


Note: Although just unlocking blocks doesn't actually free any additional 
Space in the zone, the grow zone function should still return a nonzero 
result in this case. This signals the Memory Manager to compact the 
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heap and try again to allocate the needed block. 


Warning: Depending on the circumstances in which the grow zone function is 
called, there may be a particular block within the heap zone that 
must not be moved. For this reason, it's essential that your grow 
zone function call the function GZSaveHnd (see below). 


Result codes noErr No error 

FUNCTION GZSaveHnd : Handle; [Not in ROM] 

GZSaveHnd returns a handle to a relocatable block that must not be moved by the 
grow zone function, or NIL if there is no such block. Your grow zone function 
must be sure to call GZSaveHnd; if a handle is returned, it must ensure that 
this block is not moved. 


Assembly-language note: You can find the same handle in the global 
variable GZRootHnd. 


Error Reporting 


All Memory Manager routines (including the RecoverHandle function) return a 
result code that you can examine by calling the MemError function. 


Assembly-language note: The trap RecoverHandle doesn't return a result code 
in register DO. The result code of the most recent 
call, however, is always stored in the global 
variable MemErr. 


FUNCTION MemError : OSErr; [Not in ROM] 


MemError returns the result code produced by the last Memory Manager routine 
called directly by your program. (OSErr is an Operating System Utility data type 
declared as INTEGER. ) 


Assemby-language note: To get a routine's result code from assembly Language, 
look in register DO on return from the routine (except 
for certain routines as noted). 


Miscellaneous Routines 
PROCEDURE BlockMove (sourcePtr,destPtr: Ptr; byteCount: Size); 


Trap macro —_BlockMove 
On entry AQ: sourcePtr (pointer) 
Al: destPtr (pointer) 
DO: byteCount (long word) 
On exit DO: result code (word) 
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BlockMove moves a block of byteCount consecutive bytes from the address 
designated by sourcePtr to that designated by destPtr. No pointers are updated. 
BlockMove works correctly even if the source and destination blocks overlap. 


Result codes noErr No error 
FUNCTION TopMem : Ptr; [Not in ROM] 


On a Macintosh 128K or 512K, TopMem returns a pointer to the end of RAM; on the 
Macintosh XL, it returns a pointer to the end of the memory available for use by 
the application. 


Assembly-language note: This value is stored in the global variable MemTop. 
PROCEDURE MoveHHi (h: Handle); [Not in 64K ROM] 


Trap macro —_MoveHHi 
On entry AO: h (handle) 
On exit DO: result code (word) 


MoveHHi moves the relocatable block whose handle is h toward the top of the 
current heap zone, until the block hits either a nonrelocatable block, a locked 
relocatable block, or the last block in the current heap zone. By calling 
MoveHHi before you lock a relocatable block, you can avoid fragmentation of the 
heap, as well as make room for future pointers as low in the heap as possible. 


Result codes noErr No error 
nilHandleErr NIL master pointer 
memLockedErr Block is locked 


FUNCTION MaxBlock : LONGINT; 


Trap macro _MaxBlock 
_MaxBlock ,SYS (applies to system heap) 
On exit DO: function result (word) 


MaxBlock returns the maximum contiguous space in bytes that could be obtained by 
compacting the current zone (without actually doing the compaction). 


PROCEDURE PurgeSpace (VAR total,contig: LONGINT); 


Trap macro —PurgeSpace 

_PurgeSpace ,SYS (applies to system heap) 
On exit AQ: contig (long word) 

DO: total (long word) 


PurgeSpace returns in total the total amount of space in bytes that could be 
obtained by a general purge (without actually doing the purge); this amount 
includes space that is already free. The maximum contiguous space in bytes 
(including already free space) that could be obtained by a purge is returned in 
contig. 


FUNCTION StackSpace : LONGINT; 


Trap macro _StackSpace 
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On exit DO: function result (word) 


StackSpace returns the current amount of stack space between the current stack 
pointer and the application heap (at the instant of return from the trap). 


Advanced Routine 
FUNCTION NewEmptyHandle : Handle; 


Trap macro —_NewEmptyHandle 

_NewEmptyHandle ,SYS (applies to system heap) 
On exit AO: function result (handle) 

DO: result code (word) 


NewEmptyHandle is similar in function to NewHandle except that it does not 
allocate any space; the handle returned is empty (in other words, it points to a 
NIL master pointer). NewEmptyHandle is used extensively by the Resource Manager; 
you may not need to use it. 
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CREATING A HEAP ZONE ON THE STACK 


The following code is an example of how advanced programmers can get the space 
for a new heap zone from the stack: 


CONST zoneSize = 2048; 
VAR zoneArea: PACKED ARRAY[1..zoneSize] OF SignedByte; 
stackZone: THz; 
Limit: Ptr; 
stackZone := @zoneArea; 
Limit := POINTER(ORD(stackZone)+zoneSize) ; 
InitZone(NIL,16, Limit ,@zoneArea) 


The heap zone created by this method will be usable until the routine containing 
this code is completed (because its variables will then be released). 


Assembly-language note: Here's how you might do the same thing in 
assembly language: 


zoneSize .EQU 2048 


MOVE.L SP,A2 ;save stack pointer for limit 
SUB.W #zoneSize,SP ;make room on stack 
MOVE.L SP,Al1 ;save stack pointer for start 
MOVE.L Al,stackZone ;store as zone pointer 
SUB.W #14,SP ;allocate space on stack 
CLR.L  pGrowZone(SP) ;NIL grow zone function 
MOVE.W #16,cMoreMasters(SP) ;16 master pointers 
MOVE.L A2,limitPtr(SP) ;pointer to 

; zone trailer 
MOVE.L Al,startPtr(SP) ;pointer to first 

; byte of zone 
MOVE.L SP,A0 ;point to argument block 
_InitZone ;create zone 1 


ADD.W  #14,SP ;pop arguments off stack 
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SUMMARY OF THE MEMORY MANAGER 


Constants 
CONST 


{ Result codes } 


memROZErr = -99; {operation on a read-only zone} 

memFullErr = -108; {not enough room in heap zone} 

memLockedErr = -117; {block is locked} 

memPurErr = -112; {attempt to purge a locked block} 

memWZErr = -111; {attempt to operate on a free block} 

nilHandleErr = -109; {NIL master pointer} 

noErr = 0; {no error} 

Data Types 
TYPE 

SignedByte = -128..127; 

Byte = 0..255; 

Ptr = *“SignedByte; 

Handle = SPC 

Str255 = STRING[255]; 

StringPtr = *Str255; 

StringHandle = “StringPtr; 

ProcPtr = Ptr; 

Fixed = LONGINT; 

Size = LONGINT; 

THz = “Zone; 

Zone = RECORD 
bkLim: Ptr; {zone trailer block} 
purgePtr: Ptr; {used internally} 
hFstFree: Ptr; {first free master pointer} 
zcbFree: LONGINT; {number of free bytes} 
gzProc: ProcPtr; {grow zone function} 
moreMast: INTEGER; {master pointers to allocate} 
flags: INTEGER; {used internally} 
cntRel: INTEGER; {not used} 
maxRel: INTEGER; {not used} 
cntNRel: INTEGER; {not used} 
maxNRelL: INTEGER; {not used} 
cntEmpty: INTEGER; {not used} 


cntHandles: INTEGER; {not used} 
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minCBFree: 
purgeProc: 
SparePtr: 
allocPtr: 
heapData: 


END; 


LONGINT; {not used} 

ProcPtr; {purge warning procedure} 
Ptr; {used internally} 

Ptr; {used internally} 

INTEGER {first usable byte in zone} 


Routines 


Initialization and Allocation 


PROCEDURE 
PROCEDURE 
PROCEDURE 


FUNCTION 

PROCEDURE 
PROCEDURE 
PROCEDURE 


Heap Zone 


FUNCTION 
PROCEDURE 
FUNCTION 
FUNCTION 


Allocating and Releasing 


FUNCTION 
PROCEDURE 
FUNCTION 
PROCEDURE 
FUNCTION 
FUNCTION 
PROCEDURE 


Allocating and Releasing 


InitApplZone; 
SetApplBase 
InitZone 


GetApplLimit 
SetApplLimit 
MaxApplZone; 
MoreMasters; 


Access 


GetZone : 
SetZone ( 
SystemZone : 
ApplicZone : 


NewHandle 
DisposHandle 
GetHandleSize 
SetHandleSize 
HandleZone 
RecoverHandle 
ReallocHandle 


THZ; 
THZ; 


(startPtr: Ptr); 
(pGrowZone: ProcPtr; 
LimitPtr,startPtr: 
Ptr; [Not in ROM] 
(zoneLimit: Ptr); 
[Not in 64K ROM] 


cMoreMasters: 
Ptr); 


THZ; 


hz: THz); 
[Not in ROM] 


[Not in ROM] 
Relocatable Blocks 


(logicalSize: Size) Handle; 
(h: Handle); 

(h: Handle) Size; 
(h: Handle; newSize: 
(h: THz; 
(p Handle; 
(h 


logicalSize: 


Size); 
Handle) 
Ptr) 

Handle; Size); 


Nonrelocatable Blocks 


INTEGER; 


FUNCTION NewPtr (logicalSize: Size) Ptr; 
PROCEDURE DisposPtr (p: Ptr); 

FUNCTION GetPtrSize (p Ptr) Size; 
PROCEDURE SetPtrSize (p: Ptr; newSize: Size); 
FUNCTION PtrZone (p Ptr) THz; 

Freeing Space in the Heap 

FUNCTION FreeMem : LONGINT; 

FUNCTION MaxMem (VAR grow: Size) Size; 
FUNCTION CompactMem (cbNeeded: Size) Size; 
PROCEDURE ResrvMem (cbNeeded: Size); 
PROCEDURE PurgeMem eres Size); 
PROCEDURE EmptyHandle (h Handle); 
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‘MORY MANAGE 


Properties of Relocatable Blocks 


PROCEDURE HLock (h: Handle); 

PROCEDURE HUnlock (h: Handle); 

PROCEDURE HPurge (h: Handle); 

PROCEDURE HNoPurge (h: Handle); 

PROCEDURE HSetRBit (h: Handle); 

PROCEDURE HClUrRBit (h: Handle); 

FUNCTION HGetState (h: Handle) : SignedByte; 
PROCEDURE HSetState (h: Handle; flags: SignedByte) ; 


Grow Zone Operations 


PROCEDURE SetGrowZone (growZone: ProcPtr); 
FUNCTION GZSaveHnd : Handle; [Not in ROM] 


Error Reporting 
FUNCTION MemError : OSErr; [Not in ROM] 
Miscellaneous Routines 


PROCEDURE BlockMove (sourcePtr,destPtr: Ptr; byteCount: Size); 


FUNCTION TopMem : Ptr; [Not in ROM] 
PROCEDURE MoveHHi (h: Handle); [Not in 64K ROM] 
FUNCTION MaxBlock : LONGINT; 


PROCEDURE PurgeSpace (VAR total,contig: LONGINT); 
FUNCTION StackSpace : LONGINT; 


Advanced Routine 


FUNCTION NewEmptyHandle : Handle; 


Grow Zone Function 


FUNCTION MyGrowZone (cbNeeded: Size) : LONGINT; 


Assembly-Language Information 
Constants 


; Values for tag byte of a block header 


tyBkFree .EQU 0 ;free block 
tyBkNRel . EQU 1 ;nonrelocatable block 
tyBkRel . EQU 2 ;relocatable block 


; Flags for the high-order byte of a master pointer 


lock . EQU 7 ‘lock bit 
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purge .EQU 6 ;purge bit 
resourc . EQU 5 sresource bit 


; Result codes 


memROZErr .EQU -99 ;Operation on a read-only zone 
memFullErr .EQU - 108 ;not enough room in heap zone 
memLockedErr .EQU -117 ;block is locked 

memPurErr .EQU -112 ;attempt to purge a locked block 
memWZErr .EQU -111 ;attempt to operate on a free block 
nilHandleErr .EQU - 109 ;NIL master pointer 

noErr . EQU 0 ;no error 


Zone Record Data Structure 


bkLim Pointer to zone trailer block 
hFstFree Pointer to first free master pointer 
zcbFree Number of free bytes (long) 

gzProc Address of grow zone function 
mAlLlocCnt Master pointers to allocate (word) 
purgeProc Address of purge warning procedure 
heapData First usable byte in zone 


Block Header Data Structure 


tagBC Tag byte and physical block size (long) 
handle Relocatable block: relative handle 

Nonrelocatable block: zone pointer 
blkData First byte of block contents 


Parameter Block Structure for InitZone 


startPtr Pointer to first byte in zone 

LimitPtr Pointer to first byte beyond end of zone 
cMoreMasters Number of master pointers for zone (word) 

pGrowZone Address of grow zone function 

Routines 

Trap macro On entry On exit 

_InitApplZone DO: result code (word) 
_SetApplBase AQ: startPtr (ptr) DO: result code (word) 
_InitZone AQ: ptr to parameter block DO: result code (word) 


0 startPtr (ptr) 
4 limitPtr (ptr) 
8 cMoreMasters (word) 
10 pGrowZone (ptr) 


_SetApplLimit AO: zoneLimit (ptr) DO: result code (word) 
_MaxApplZone DO: result code (word) 
_MoreMasters 

_GetZone AQ: function result (ptr) 


DO: result code (word) 
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_SetZone 
_NewHandle 


_DisposHandle 
_GetHandleSize 


_SetHandleSize 
_HandleZone 
_RecoverHandle 
_ReallocHandle 
_NewPtr 


_DisposPtr 
_GetPtrSize 


_SetPtrSize 
_PtrZone 


_FreeMem 
_MaxMem 


_CompactMem 
_ResrvMem 
_PurgeMem 
_EmptyHandle 


_HLock 
_HUntock 
_HPurge 
_HNoPurge 
_HSetRBit 
_HCUrRBit 
_HGetState 
_HSetState 


_SetGrowZone 
_BlockMove 


_MoveHHi 
_MaxBlock 
_PurgeSpace 


_StackSpace 
_NewEmptyHandle 


Variables 


DefltStack 
MinStack 


: h 
: oh 


: p 
: p 


: cbNeeded ( 
: cbNeeded (long) 
: cbNeeded ( 
: h (handle) 


h 
h 
:h 
: oh 
h 
h 
h 


: hz (ptr) 
: logicalSize (long) 


(handle) 
(handle) 


: h (handle) 
: newSize (long) 
: h (handle) 


: p (ptr) 


: h (handle) 
: logicalSize (long) 
: logicalSize (long) 


: p (ptr) 
: newSize (long) 
: p (ptr) 


long) 
long) 
handle) 


handle) 
handle) 


: h (handle) 

: flags (byte) 

: growZone (ptr) 

: sourcePtr (ptr) 
: destPtr (ptr) 

: byteCount (long) 
: h (handle) 


result code (word) 


: function result (handle) 


result code (word) 
result code (word) 


: if >=0, function result (long) 


if <0, result code (word) 
result code (word) 


: function result (ptr) 


result code (word) 


: function result (handle) 
: unchanged 


result code (word) 


: function result (ptr) 


result code (word) 
result code (word) 


: if >=0, function result (long) 


if <0, result code (word) 
result code (word) 


: function result (ptr) 


result code (word) 


: function result (long) 
: function result (long) 
: grow (long) 

: function result (long) 


result code (word) 
result code (word) 


: h (handle) 


result code ( ) 
result code ( ) 
result code (word) 
result code ( ) 
result code ( ) 
result code ( ) 
result code (word) 


: function result (byte) 


result code (word) 


result code (word) 
result code (word) 


result code (word) 


: function result (word) 
: contig (long) 

: total (long) 

: function result (word) 
: function result (word) 


Default space allotment for stack (long) 
Minimum space allotment for stack (long) 
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MemTop 


ScrnBase 
BufPtr 
CurrentA5 


CurStackBase 
ApplLimit 
HeapEnd 
ApplZone 
SysZone 
TheZone 
GZRootHnd 
MemErr 


Address of end of RAM (on Macintosh XL, end of RAM 


available to applications) 
Address of main screen buffer 
Address of end of jump table 


Address of boundary between application globals 


and application parameters 


Address of base of stack; start of application globals 


Application heap limit 

Address of end of application heap zone 
Address of application heap zone 
Address of system heap zone 

Address of current heap zone 


Handle to relocatable block not to be moved by grow zone function 


Current value of MemError (word) 
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Further Reference: 


Memory Management Intro 

Technical Note #53, MoreMasters Revisited 

Technical Note #117, Compatibility: Why & How 

Technical Note #151, System Error 33, "zcbFree has gone negative" 
Technical Note #205, MultiFinder Revisited: The 6.0 System Release 
Technical Note #212, The Joy Of Being 32-Bit Clean 

Technical Note #213, StripAddress: The Untold Story 

Technical Note #219, New Memory Manager Glue Routines 

Technical Note #233, MultiFinder and SetGrowZone 


END OF DOCUMENT 
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